Спринт 2/18 → Тема 5/6: Требования к коду → Урок 2/7
Правила оформления кода и линтеры
Оформление кода
Даже код, написанный для себя, лучше сразу делать структурированным. В какой-то момент вы обязательно захотите показать его кому-то ещё — и попадёте в неловкую ситуацию: увидев ваш код, коллега может задать вам немой вопрос — «А ты точно разработчик?».
«Соотношение времени чтения и написания кода превышает 10:1. … Из-за столь высокого соотношения наш код должен легко читаться, даже если это затрудняет его написание».Роберт Мартин, «Чистый код: создание, анализ и рефакторинг»
Чтобы код легко было читать каждому участнику команды, в группе разработки обычно принимаются правила оформления кода. Но для некоторых языков программирования правила оформления выносятся как стандарты на всё сообщество. В Python принято оформлять код по стандарту оформления кода PEP8, он используется и в проектах Яндекс Практикума.
Основные правила PEP8
- Длина строки — не более 79 символов.
- Отступы — 4 пробела.
- Стили имён соответствуют PEP8: Naming Conventions.
- Переносы строк делаются с правильными отступами.
- Бэкслеши
\для переносов не применяются. - В коде нет неиспользуемых импортов.
- Импорты отсортированы в таком порядке:
- импорты стандартной библиотеки,
- импорты сторонних библиотек,
- импорты модулей текущего проекта.
- Функции верхнего уровня (не вложенные) и определения классов отделены друг от друга двумя пустыми строчками.
- Определения методов внутри класса отделены одной пустой строкой.
- В проекте использован одинаковый стиль кавычек: или везде одинарные, в которые вложены двойные (выбран как основной для проектов на курсе), или везде двойные, в которые вложены одинарные.
❗ Более полный список правил есть в шпаргалке. Скачайте её и держите под рукой.
Для отслеживания правил оформления кода есть специальные программы: линтеры.
Изначально linter (или lint remover) — это ролик для чистки одежды, вот такая штука:
В программировании линтерами принято называть инструменты для анализа кода, которые помогают находить места, где код не соответствует указанному стандарту.
Для разных проектов может понадобиться использование разных линтеров, поэтому линтеры стоит устанавливать в виртуальное окружение проекта.
Как включить линтер в VSCode
Когда в VSCode вы открываете файл с расширением .py, в правом нижнем углу интерфейса может появиться всплывающее окно с предложением установить расширения для Python, в том числе и линтеры.
Если вы случайно закрыли это окошко или оно не появилось вовсе — не беда, этот набор расширений доступен в разделе «Рекомендуемые» в панели расширений VSCode (она открывается с помощью горячих клавиш Ctrl+Shift+X).
Выбрать и активировать нужный линтер можно с помощью командной строки VSCode (Command Palette, вызывается через Ctrl+Shift+P).
Введите в командную строку текст Python: Select Linter, выберите пункт, который полностью совпадает с поисковым запросом, и нажмите Enter.
Появится список доступных линтеров (он может отличаться от списка на картинке ниже):
Выберите линтер flake8. Он объединяет в себе несколько анализаторов кода (pycodestyle, pyflakes и mccabe). Сейчас это один из самых популярных линтеров для Python. В курсе ваши проекты будут проверяться именно с помощью него.
В нижней части интерфейса может появиться окошко с предложением установить линтер. Соглашайтесь. После этого линтер должен заработать.
Линтер немедленно сообщит вам о проблемах в файле: даст описание ошибок во вкладке Problems…
…и подчеркнёт проблемные места прямо в коде:
Линтер не включился: что делать?
Бывает, что не получается включить линтер через графический интерфейс. Чаще всего это связано с правами доступа к системным файлам на компьютере. В таком случае можно работать с линтером через терминал по вот такому плану:
- Запускаете виртуальное окружение проекта.
- Устанавливаете flake8 через пакетный менеджер pip:BASH
- Проверяете, выполнена ли установка: запрашиваете через терминал версию утилиты flake8:BASHЕсли всё в порядке — вы увидите в консоли примерно такой ответ:PYTHON
- Начинаете проверку кода через flake8. Для этого при запущенном виртуальном окружении вводите в терминал команду:BASHВ терминал выведется список несоответствий кода стандарту PEP8; он будет выглядеть приблизительно так:BASHВ каждой строчке указано место, где совершена ошибка, код ошибки и её краткое описание:BASH
Все коды ошибок несоответствия стандарту описаны в правилах flake8; там же даны ссылки на документацию с примерами правильного оформления кода.
Дополнения для flake8
Для flake8 можно установить дополнения. Задача этих дополнений — проверять на соответствие стандарту конкретные части кода.
Дополнения устанавливаются из консоли через pip.
Мы рекомендуем установить следующие дополнения:
- pep8-naming — проверяет имена классов, функций и переменных на соответствие PEP8;
- flake8-broken-line — отслеживает применение устаревших переносов (через обратный слеш
\); - flake8-return — проверяет значения, возвращаемые функциями;
- flake8-isort — проверяет правильность порядка импортов.
Задание
Оформите код в файле main.py проекта character_creation_module по стандарту PEP8. Для этого исправьте все ошибки, которые выводит утилита flake8.
Когда линтер будет «доволен» вашим кодом нажимайте кнопку «Дальше».
В итоге ваш код должен выглядеть примерно так:
PYTHON
Сравните результат своей работы с листингом и поправьте код, если заметите очевидные различия.
Когда справитесь с этой задачей, отправьте код на GitHub. Находясь в виртуальном окружении проекта, введите последовательно команды:
git add .git commit -m 'code according to PEP8'git push
Это действие мы проверить не сможем, поэтому оно остаётся под вашу ответственность. Проект со всеми изменениями пригодится вам в конце этого спринта.
Следуйте установленным стандартам при оформлении кода. Благодаря этому ваш код будет проще поддерживать и развивать. А ещё это поможет свести к минимуму количество ошибок при разработке.